home *** CD-ROM | disk | FTP | other *** search
/ Aminet 52 / Aminet 52 (2002)(GTI - Schatztruhe)[!][Dec 2002].iso / Aminet / misc / emu / Apex-src.lha / CONVENT.TXT < prev    next >
Text File  |  2001-09-30  |  8KB  |  183 lines
  1. CONVENT.TXT    FEB-01-88
  2.  
  3.             PROGRAMMING CONVENTIONS
  4.  
  5. The importance of adopting and sticking to conventions cannot be overstated.
  6. Assembly language programming needs to be restricted. This is the main idea
  7. behind structured programming. Assembly language programming is like sculpting a
  8. blob of clay. What is needed are some basic structures like the integrated
  9. circuit industry have developed. Indeed, the integrated circuit industry has
  10. advanced far faster the the software industry.
  11.  
  12. High level languages are a powerful tool for reducing software costs. Computer
  13. commands can be specified in a succinct and consistent manner. Collections of
  14. general purpose, easy-to-understand, routines (libraries) are the key factor in
  15. reducing software costs.
  16.  
  17. Realize that exceptions to the following rules will cause confusion, and that
  18. now-a-days, the most important priority in programming is usually to minimize
  19. confusion. The traditional concerns about memory consumption and speed-of-
  20. execution are diminishing.
  21.  
  22. Code which does not follow these conventions cannot be tolerated even if it
  23. works. It must be modified to conform to these conventions. It is interesting to
  24. note that it was more difficult to modify Peter's code, in the case of BYTEIO,
  25. than it was to rewrite it completely from scratch as in the case of CONHAN.
  26.  
  27.  
  28. ASSEMBLY LANGUAGE CODE
  29.  
  30. Only resort to assembly language if XPL cannot be used for some reason.
  31.  
  32. Subroutines must preserve the contents of registers or list the bombed registers
  33. as part of the description of what the routine does. Contrary to many 68000
  34. programmer's conventions, there is no such thing as scratch registers which do
  35. not have to be preserved across subroutine calls.
  36.  
  37. Subroutines should have one entry point and one exit point. (The use of the
  38. 'RETURN' statement in XPL should be avoided except for returning values at the
  39. end of a function.) Subroutine entry points are given global names which are
  40. distinct from internal line number names, which have numeric suffixes.
  41.  
  42. Use BSR and BRA to refer to locations within a module; use JSR and JMP to refer
  43. to locations outside a module. This will help make the module relocatable and
  44. costs nothing. (Use PC relative addressing when referring to data within the
  45. module.) Keep all variables together and at the beginning of a module.
  46.  
  47.  
  48. ASSEMBLY LANGUAGE DATA
  49.  
  50. In addition to the rules for structured programming there need to be some rules
  51. for data manipulation.
  52.  
  53. The 68000 is much more register oriented than the 6502. It is efficient for a
  54. routine to load up the registers with variables and start crunching. Input and
  55. output variables (arguments) can be passed in the registers.
  56.  
  57. A significant difference between the 6502 and the 68000 is the convention on
  58. byte order. The 6502 has the least significant byte first, while the 68000 has
  59. the most significant byte first. 68000 code should not use 6502 conventions, and
  60. vice versa.
  61.  
  62.  
  63. ARGUMENTS
  64.  
  65. Arguments (subroutine input and output variables) can be passed in registers, on
  66. the stack or in global variables. Using global variables is the least desirable
  67. way. If they are used they must be clearly commented as inputs or outputs.
  68.  
  69. It should be impossible (or at least difficult) to blow up an XPL program. Hence
  70. all variables which originate with XPL code, such as device numbers, should be
  71. checked for validity before they are used. Currently, function codes do not
  72. originate in XPL code and consequently do not need to be checked (although the
  73. code will surely blow if they're wrong).
  74.  
  75. When a value in a register is returned from a subroutine, the entire long word
  76. is assumed to be correct even if only the lower byte is used. (The high bytes
  77. are zero in this case).
  78.  
  79. A single boolean argument should be passed in a data register. (Note that most
  80. operations -- even MOVE -- clear the C and Z bits, and there is no branch on
  81. X.) A boolean value may be returned in the same manner. Pure booleans should be
  82. used. That is, 'FALSE' = $00000000 and 'TRUE' = $FFFFFFFF. (Note that NOT.L
  83. of $FF is not necessarily equal to $00000000, it might be equal to $FFFFFF00.
  84.  
  85.  
  86. BUFFERS
  87.  
  88. FIFO buffers will always be implemented the same way. The first location of the
  89. buffer will always be the name of the buffer. The last location + 1 will always
  90. be used as the end. (This location will be clearly distinguished from the acutal
  91. end which is the last location.) The address registers (An) will be used to
  92. directly access the contents, that is, indexing off the base address will not be
  93. used (except in multi-dimensional arrays where the index is the same for several
  94. sub-arrays). The "A" register will always point to the next location to be
  95. processed. If you are filling a FIFO then the "A" register will always point to
  96. an empty location. If you are emptying a FIFO then the "A" register will always
  97. point to the location about to be emptied. The pointer will always be
  98. incremented.
  99.  
  100.  
  101. APEX DIRECTORY STRUCTURE
  102.  
  103. The jumbled order of the Apex directories will cause a tremendous amount of
  104. confusion in the future. This must be weighed against the value of maintaining
  105. compatible directories between 6502 and 68000 systems (which is quite useful
  106. when using XDUP).
  107.  
  108. The 6502 systems are not going to be replaced overnight; it will take years. A
  109. certain amount of data will be exchanged between the two systems. Right now
  110. there is a very crude RS-232 link. It is expected that Iomegas will be common to
  111. both systems. A directory conversion routine could be used. The major conflicts
  112. are the reversed order of the bytes in 16-bit values, and the separate, extended
  113. directory caused by the Apple RWTS boot.
  114.  
  115. Conversion routines should be used.
  116.  
  117.  
  118. DAMN LINE FEEDS
  119.  
  120. Line feeds are a classic example of what happens when conventions clash. Line
  121. feeds are trivial, but they have caused an unbelievable amount of trouble. Now,
  122. within the Apex software environment there is no such thing as a line feed <LF>.
  123. There is only a carriage return <CR>, which means advance to the beginning of
  124. the next line.
  125.  
  126. The hardware environment is different. To hardware, a <CR> means move to the
  127. start of the current line, and a <LF> means move down one line. It is the
  128. purpose of the device handler to cause a <CR> from the software to move the
  129. hardware to the start of the next line by whatever means is required.
  130.  
  131.  
  132. NAMES
  133.  
  134. Variable names should be nouns; procedure names should be verbs. Descriptive
  135. adjectives should be added at the end, not at the beginning as is natural with
  136. English.
  137.  
  138.     Variables        Procedures
  139.     LINE            COUNT
  140.     ERROR3            DELETE
  141.     ERROR_FATAL        DRAWLINE
  142.  
  143. Use plural nouns to stand for the number of something; use singular nouns for
  144. array names (parenthesis make arrays obvious).
  145.  
  146.     NAME        \Array of names
  147.     NAMES        \Total number of elements in NAME
  148.     NAMEMIN        \The minimum subscript (usually = 0)
  149.     NAMEMAX        \The maximum subscript (usually = NAMES -1)
  150.  
  151.  
  152. MISCELLANY
  153.  
  154. Don't underestimate the difficulty of designing an effective human interface.
  155. The simple scrolling technique has many subtle advantages over a paging
  156. technique. Avoid using form feeds which erase useful information. It is amazing
  157. how often they are used to immediately erase an error message before it can be
  158. read.
  159.  
  160. Use defensive programming. Whenever a comparison for equality is made it usually
  161. costs nothing to, for example, test for greater than or equal in case the
  162. greater than situation ever arrises.
  163.  
  164. When using the 68000, the data type "word" is to be avoided. XPL does not
  165. recognize it, it usually is not a significant saving in place of a long word,
  166. and it simplifies things to eliminate it altogether.
  167.  
  168. Distinguish between a pointer and an index. A pointer contains an absolute
  169. address, while an index is added to a base address to get the desired absolute
  170. address. "Index" is another name for "subscript".
  171.  
  172.  
  173. PROGRAMMERS VS. PEOPLE
  174.  
  175. People always count one, two, three..., but the intelligent programmer isn't
  176. sure whether to start with one or zero. Distinguish between the programmer's
  177. world and the people world.
  178.  
  179. Have a very good reason if you change a convention.
  180. ero. Distinguish between the programmer's
  181. world and the people world.
  182.  
  183. Have a very good reaso